home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / util / Collection.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  14.7 KB  |  358 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Collection.java    1.25 98/09/30
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.util;
  16.  
  17. /**
  18.  * The root interface in the <i>collection hierarchy</i>.  A collection
  19.  * represents a group of objects, known as its <i>elements</i>.  Some
  20.  * collections allow duplicate elements and others do not.  Some are ordered
  21.  * and others unordered.  The JDK does not provide any <i>direct</i>
  22.  * implementations of this interface: it provides implementations of more
  23.  * specific subinterfaces like <tt>Set</tt> and <tt>List</tt>.  This interface
  24.  * is typically used to pass collections around and manipulate them where
  25.  * maximum generality is desired.<p>
  26.  *
  27.  * <i>Bags</i> or <i>multisets</i> (unordered collections that may contain
  28.  * duplicate elements) should implement this interface directly.<p>
  29.  *
  30.  * All general-purpose <tt>Collection</tt> implementation classes (which
  31.  * typically implement <tt>Collection</tt> indirectly through one of its
  32.  * subinterfaces) should provide two "standard" constructors: a void (no
  33.  * arguments) constructor, which creates an empty collection, and a
  34.  * constructor with a single argument of type <tt>Collection</tt>, which
  35.  * creates a new collection with the same elements as its argument.  In
  36.  * effect, the latter constructor allows the user to copy any collection,
  37.  * producing an equivalent collection of the desired implementation type.
  38.  * There is no way to enforce this convention (as interfaces cannot contain
  39.  * constructors) but all of the general-purpose <tt>Collection</tt>
  40.  * implementations in the JDK comply.<p>
  41.  *
  42.  * @author  Josh Bloch
  43.  * @version 1.25 09/30/98
  44.  * @see        Set
  45.  * @see        List
  46.  * @see        Map
  47.  * @see        SortedSet
  48.  * @see        SortedMap
  49.  * @see        HashSet
  50.  * @see        TreeSet
  51.  * @see        ArrayList
  52.  * @see        LinkedList
  53.  * @see        Vector
  54.  * @see     Collections
  55.  * @see        Arrays
  56.  * @see        AbstractCollection
  57.  * @since   JDK1.2
  58.  */
  59.  
  60. public interface Collection {
  61.     // Query Operations
  62.  
  63.     /**
  64.      * Returns the number of elements in this collection.  If this collection
  65.      * contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
  66.      * <tt>Integer.MAX_VALUE</tt>.
  67.      * 
  68.      * @return the number of elements in this collection
  69.      */
  70.     int size();
  71.  
  72.     /**
  73.      * Returns <tt>true</tt> if this collection contains no elements.
  74.      *
  75.      * @returns <tt>true</tt> if this collection contains no elements
  76.      */
  77.     boolean isEmpty();
  78.  
  79.     /**
  80.      * Returns <tt>true</tt> if this collection contains the specified
  81.      * element.  More formally, returns <tt>true</tt> if and only if this
  82.      * collection contains at least one element <tt>e</tt> such that
  83.      * <tt>(o==null ? e==null : o.equals(e))</tt>.
  84.      *
  85.      * @param o element whose presence in this collection is to be tested.
  86.      * @return <tt>true</tt> if this collection contains the specified
  87.      *         element
  88.      */
  89.     boolean contains(Object o);
  90.  
  91.     /**
  92.      * Returns an iterator over the elements in this collection.  There are no
  93.      * guarantees concerning the order in which the elements are returned
  94.      * (unless this collection is an instance of some class that provides a
  95.      * guarantee).
  96.      * 
  97.      * @returns an <tt>Iterator</tt> over the elements in this collection
  98.      */
  99.     Iterator iterator();
  100.  
  101.     /**
  102.      * Returns an array containing all of the elements in this collection.  If
  103.      * the collection makes any guarantees as to what order its elements are
  104.      * returned by its iterator, this method must return the elements in the
  105.      * same order.<p>
  106.      *
  107.      * The returned array will be "safe" in that no references to it are
  108.      * maintained by this collection.  (In other words, this method must
  109.      * allocate a new array even if this collection is backed by an array).
  110.      * The caller is thus free to modify the returned array.<p>
  111.      *
  112.      * This method acts as bridge between array-based and collection-based
  113.      * APIs.
  114.      *
  115.      * @return an array containing all of the elements in this collection
  116.      */
  117.     Object[] toArray();
  118.  
  119.     /**
  120.      * Returns an array containing all of the elements in this collection
  121.      * whose runtime type is that of the specified array.  If the collection
  122.      * fits in the specified array, it is returned therein.  Otherwise, a new
  123.      * array is allocated with the runtime type of the specified array and the
  124.      * size of this collection.<p>
  125.      *
  126.      * If this collection fits in the specified array with room to spare
  127.      * (i.e., the array has more elements than this collection), the element
  128.      * in the array immediately following the end of the collection is set to
  129.      * <tt>null</tt>.  This is useful in determining the length of this
  130.      * collection <i>only</i> if the caller knows that this collection does
  131.      * not contain any <tt>null</tt> elements.)<p>
  132.      *
  133.      * If this collection makes any guarantees as to what order its elements
  134.      * are returned by its iterator, this method must return the elements in
  135.      * the same order.<p>
  136.      *
  137.      * Like the <tt>toArray</tt> method, this method acts as bridge between
  138.      * array-based and collection-based APIs.  Further, this method allows
  139.      * precise control over the runtime type of the output array, and may,
  140.      * under certain circumstances, be used to save allocation costs<p>
  141.      *
  142.      * Suppose <tt>l</tt> is a <tt>List</tt> known to contain only strings.
  143.      * The following code can be used to dump the list into a newly allocated
  144.      * array of <tt>String</tt>:
  145.      *
  146.      * <pre>
  147.      *     String[] x = (String[]) v.toArray(new String[0]);
  148.      * </pre><p>
  149.      *
  150.      * Note that <tt>toArray(new Object[0])</tt> is identical in function to
  151.      * <tt>toArray()</tt>.
  152.      *
  153.      * @param the array into which the elements of this collection are to be
  154.      *        stored, if it is big enough; otherwise, a new array of the same
  155.      *        runtime type is allocated for this purpose.
  156.      * @return an array containing the elements of this collection
  157.      * 
  158.      * @throws ArrayStoreException the runtime type of the specified array is
  159.      *         not a supertype of the runtime type of every element in this
  160.      *         collection.
  161.      */
  162.     
  163.     Object[] toArray(Object a[]);
  164.  
  165.     // Modification Operations
  166.  
  167.     /**
  168.      * Ensures that this collection contains the specified element (optional
  169.      * operation).  Returns <tt>true</tt> if this collection changed as a
  170.      * result of the call.  (Returns <tt>false</tt> if this collection does
  171.      * not permit duplicates and already contains the specified element.)<p>
  172.      *
  173.      * Collections that support this operation may place limitations on what
  174.      * elements may be added to this collection.  In particular, some
  175.      * collections will refuse to add <tt>null</tt> elements, and others will
  176.      * impose restrictions on the type of elements that may be added.
  177.      * Collection classes should clearly specify in their documentation any
  178.      * restrictions on what elements may be added.<p>
  179.      *
  180.      * If a collection refuses to add a particular element for any reason
  181.      * other than that it already contains the element, it <i>must</i> throw
  182.      * an exception (rather than returning <tt>false</tt>).  This preserves
  183.      * the invariant that a collection always contains the specified element
  184.      * after this call returns.
  185.      *
  186.      * @param o element whose presence in this collection is to be ensured.
  187.      * @return <tt>true</tt> if this collection changed as a result of the
  188.      *         call
  189.      * 
  190.      * @throws UnsupportedOperationException add is not supported by this
  191.      *         collection.
  192.      * @throws ClassCastException class of the specified element prevents it
  193.      *         from being added to this collection.
  194.      * @throws IllegalArgumentException some aspect of this element prevents
  195.      *          it from being added to this collection.
  196.      */
  197.     boolean add(Object o);
  198.  
  199.     /**
  200.      * Removes a single instance of the specified element from this
  201.      * collection, if it is present (optional operation).  More formally,
  202.      * removes an element <tt>e</tt> such that <tt>(o==null ?  e==null :
  203.      * o.equals(e))</tt>, if this collection contains one or more such
  204.      * elements.  Returns true if this collection contained the specified
  205.      * element (or equivalently, if this collection changed as a result of the
  206.      * call).
  207.      *
  208.      * @param o element to be removed from this collection, if present.
  209.      * @return <tt>true</tt> if this collection changed as a result of the
  210.      *         call
  211.      * 
  212.      * @throws UnsupportedOperationException remove is not supported by this
  213.      *         collection.
  214.      */
  215.     boolean remove(Object o);
  216.  
  217.  
  218.     // Bulk Operations
  219.  
  220.     /**
  221.      * Returns <tt>true</tt> if this collection contains all of the elements
  222.      * in the specified collection.
  223.      *
  224.      * @param c collection to be checked for containment in this collection.
  225.      * @return <tt>true</tt> if this collection contains all of the elements
  226.      *           in the specified collection
  227.      * @see #contains(Object)
  228.      */
  229.     boolean containsAll(Collection c);
  230.  
  231.     /**
  232.      * Adds all of the elements in the specified collection to this collection
  233.      * (optional operation).  The behavior of this operation is undefined if
  234.      * the specified collection is modified while the operation is in progress.
  235.      * (This implies that the behavior of this call is undefined if the
  236.      * specified collection is this collection, and this collection is
  237.      * nonempty.)
  238.      *
  239.      * @param c elements to be inserted into this collection.
  240.      * @return <tt>true</tt> if this collection changed as a result of the
  241.      *         call
  242.      * 
  243.      * @throws UnsupportedOperationException if this collection does not
  244.      *         support the <tt>addAll</tt> method.
  245.      * @throws ClassCastException if the class of an element of the specified
  246.      *            collection prevents it from being added to this collection.
  247.      * @throws IllegalArgumentException some aspect of an element of the
  248.      *           specified collection prevents it from being added to this
  249.      *           collection.
  250.      * 
  251.      * @see #add(Object)
  252.      */
  253.     boolean addAll(Collection c);
  254.  
  255.     /**
  256.      * 
  257.      * Removes all this collection's elements that are also contained in the
  258.      * specified collection (optional operation).  After this call returns,
  259.      * this collection will contain no elements in common with the specified
  260.      * collection.
  261.      *
  262.      * @param c elements to be removed from this collection.
  263.      * @return <tt>true</tt> if this collection changed as a result of the
  264.      *         call
  265.      * 
  266.      * @throws UnsupportedOperationException if the <tt>removeAll</tt> method
  267.      *            is not supported by this collection.
  268.      * 
  269.      * @see #remove(Object)
  270.      * @see #contains(Object)
  271.      */
  272.     boolean removeAll(Collection c);
  273.  
  274.     /**
  275.      * Retains only the elements in this collection that are contained in the
  276.      * specified collection (optional operation).  In other words, removes from
  277.      * this collection all of its elements that are not contained in the
  278.      * specified collection.
  279.      *
  280.      * @param c elements to be retained in this collection.
  281.      * @return <tt>true</tt> if this collection changed as a result of the
  282.      *         call
  283.      * 
  284.      * @throws UnsupportedOperationException if the <tt>retainAll</tt> method
  285.      *            is not supported by this Collection.
  286.      * 
  287.      * @see #remove(Object)
  288.      * @see #contains(Object)
  289.      */
  290.     boolean retainAll(Collection c);
  291.  
  292.     /**
  293.      * Removes all of the elements from this collection (optional operation).
  294.      * This collection will be empty after this method returns unless it
  295.      * throws an exception.
  296.      *
  297.      * @throws UnsupportedOperationException if the <tt>clear</tt> method is
  298.      *         not supported by this collection.
  299.      */
  300.     void clear();
  301.  
  302.  
  303.     // Comparison and hashing
  304.  
  305.     /**
  306.      * Compares the specified object with this collection for equality. <p>
  307.      *
  308.      * While the <tt>Collection</tt> interface adds no stipulations to the
  309.      * general contract for the <tt>Object.equals</tt>, programmers who
  310.      * implement the <tt>Collection</tt> interface "directly" (in other words,
  311.      * create a class that is a <tt>Collection</tt> but is not a <tt>Set</tt>
  312.      * or a <tt>List</tt>) must exercise care if they choose to override the
  313.      * <tt>Object.equals</tt>.  It is not necessary to do so, and the simplest
  314.      * course of action is to rely on <tt>Object</tt>'s implementation, but
  315.      * the implementer may wish to implement a "value comparison" in place of
  316.      * the default "reference comparison."  (The <tt>List</tt> and
  317.      * <tt>Set</tt> interfaces mandate such value comparisons.)<p>
  318.      *
  319.      * The general contract for the <tt>Object.equals</tt> method states that
  320.      * equals must be symmetric (in other words, <tt>a.equals(b)</tt> if and
  321.      * only if <tt>b.equals(a)</tt>).  The contracts for <tt>List.equals</tt>
  322.      * and <tt>Set.equals</tt> state that lists are only equal to other lists,
  323.      * and sets to other sets.  Thus, a custom <tt>equals</tt> method for a
  324.      * collection class that implements neither the <tt>List</tt> nor
  325.      * <tt>Set</tt> interface must return <tt>false</tt> when this collection
  326.      * is compared to any list or set.  (By the same logic, it is not possible
  327.      * to write a class that correctly implements both the <tt>Set</tt> and
  328.      * <tt>List</tt> interfaces.)
  329.      *
  330.      * @param o Object to be compared for equality with this collection.
  331.      * @return <tt>true</tt> if the specified object is equal to this
  332.      * collection
  333.      * 
  334.      * @see Object#equals(Object)
  335.      * @see Set#equals(Object)
  336.      * @see List#equals(Object)
  337.      */
  338.     boolean equals(Object o);
  339.  
  340.     /**
  341.      * 
  342.      * Returns the hash code value for this collection.  While the
  343.      * <tt>Collection</tt> interface adds no stipulations to the general
  344.      * contract for the <tt>Object.hashCode</tt> method, programmers should
  345.      * take note that any class that overrides the <tt>Object.equals</tt>
  346.      * method must also override the <tt>Object.hashCode</tt> method in order
  347.      * to satisfy the general contract for the <tt>Object.hashCode</tt>method.
  348.      * In particular, <tt>c1.equals(c2)</tt> implies that
  349.      * <tt>c1.hashCode()==c2.hashCode()</tt>.
  350.      *
  351.      * @return the hash code value for this collection
  352.      * 
  353.      * @see Object#hashCode()
  354.      * @see Object#equals(Object)
  355.      */
  356.     int hashCode();
  357. }
  358.